Dify 1.17 升级实测（三）：循环内人工审批与图片直传实测——两个高频场景的新解法

📖 摘要：1.17 把两个高频交付场景的能力补齐了：人工输入表单（HITL）终于能在 Iteration 循环内逐项暂停、逐项确认——审批流可以直接做了；图片直传多模态模型也打通了——上传、文件变量、vision 配置、视觉模型识别一条链路。但这两块都有新格式和新坑：迭代节点 DSL 大改、output_selector 收集格式、文件访问控制。本文是完整实测记录。

一、实验目的：两个被问过很多次的场景

做交付这些年，被问得最多的两个需求：

1. 审批流：一批任务，每一项都要人工确认，能不能在循环里逐项暂停等确认？
2. 图片理解：用户传一张图，让模型看——怎么传？哪个模型能看？

1.16 时代这两个需求都「能凑合」：审批流靠拆解成多次调用，图片得先转 URL 再想办法塞进提示词。1.17 把两个都做成了原生能力。本文实测这两条链路，验证它们到底能不能直接用于交付。

二、场景设计：两个贴近业务的实验

实验 A（审批流）：输入「任务A,任务B」，工作流用 Iteration 遍历每项任务，每项暂停弹人工确认表单，确认后继续下一项，最终输出每项的人工确认结果数组。

实验 B（图片理解）：用户上传一张测试图片（蓝色背景 + 左上角红色方块），LLM 节点配视觉模型 qwen-vl-plus，直传图片让它描述内容。

三、整体架构：两条链路

四、迭代内人工输入（HITL in Iteration）

4.1 先说迭代格式：1.17 大改

实验第一件事就撞上了破坏性变更——1.17 的 iteration 节点格式和 1.16 完全不同：

# 1.17 的迭代节点（实测格式）

- id: iter_check

  data:

    type: iteration

    start_node_id: iter_start          # 迭代开始节点 ID

    iterator_selector: ["cd_items", "items"]    # 遍历的数组

    output_selector: ["cd_build", "result"]     # 收集每次迭代的输出（节点.字段）

    is_parallel: false

    parallel_nums: 10

    error_handle_mode: terminated

    flatten_output: true



# 迭代开始节点（类型也变了）

- id: iter_start

  data:

    type: iteration-start              # 1.16 是 custom-iteration-start

三个变化：items 变 iterator_selector、output 变 output_selector + start_node_id、迭代开始标记类型变了。迭代内节点不再需要 isInIteration/iteration_id/parentId 标记——范围由 start_node_id 界定，这是 1.17 的简化。

4.2 迭代内放人工输入：逐项暂停

工作流结构：code 节点生成数组 → Iteration 遍历 → 迭代内是「人工确认表单」→「组装结果」→ 迭代输出。

人工输入节点格式与 1.16 兼容（type=human-input / form_content / inputs / user_actions / timeout），迭代内引用当前项用 {{#iter_check.item#}}：

- id: hi_confirm

  data:

    type: human-input

    title: 逐项确认

    form_content: "请确认任务「{{#iter_check.item#}}」：\n{{#confirm#}}"

    inputs:

      - type: paragraph

        label: 确认意见

        required: true

        output_variable_name: confirm

        default: {type: constant, value: "同意执行"}

    user_actions:

      - {id: approve, title: 同意, button_style: primary}

      - {id: reject, title: 拒绝, button_style: default}

    timeout: 1

    timeout_unit: hour

4.3 运行与恢复：每次迭代独立暂停

运行后工作流在第一个 human-input 处暂停（status=paused，elapsed 约 0.7 秒）。恢复链路三步：

1. GET /console/api/workflow/{run_id}/pause-details

   → paused_nodes[0].pause_type.form_id



2. 查数据库拿表单令牌（API 不给！）：

   select access_token from human_input_form_recipients where form_id='...'



3. POST /console/api/form/human_input/{form_token}

   {"inputs": {"confirm": "同意执行任务A"}, "action": "approve"}

提交后工作流恢复，进入第二次迭代再次暂停——每次迭代一个独立表单。两项都确认后，流程跑完：

{"result": ["任务A|同意任务1", "任务B|同意任务2"]}

逐项确认结果正确收集。1.16 时代人工输入恢复时的竞态 bug（Client response stream closed）在 1.17 未复现——两次暂停恢复全稳定。

4.4 迭代输出收集的坑

output_selector 是本次实验最隐蔽的坑：必须写 [节点id, 字段] 格式（["cd_build", "result"]）。我们第一版写成了输出变量名 ["iter_result"]——运行成功、不报错，但迭代输出数组全是 null。静默失败，验收时容易漏。

五、多模态图片直传

5.1 三个配置点

# 1. 开始节点的文件变量

- id: start

  data:

    type: start

    variables:

      - label: 图片

        type: file

        variable: image

        required: true

        allowed_file_types: ["image"]   # 分类枚举：image/document/audio/video/custom



# 2. LLM 节点开 vision

- id: llm_v

  data:

    type: llm

    model: {provider: langgenius/tongyi/tongyi, name: qwen-vl-plus, mode: chat}

    prompt_template:

      - role: user

        text: "请描述这张图片的内容，用中文。"

    vision:

      enabled: true

      configs:

        variable_selector: ["start", "image"]

        detail: high

注意 allowed_file_types 是分类枚举（image/document/audio/video/custom），不是 MIME 类型——写 image/png 直接 400。

5.2 上传链路：必须走 service API

图片上传有个访问控制的坑：console 后台的上传接口（/console/api/files/upload）传的文件，service API 运行时引用会报 Invalid upload file——两套体系隔离。

正确姿势：用应用密钥走 service API 上传：

POST /v1/files/upload   （Authorization: Bearer 应用密钥，multipart 表单）

→ 拿到 upload_file_id



运行传参（file 变量是单个对象，不是数组）：

{"image": {"type": "image", "transfer_method": "local_file", "upload_file_id": "..."}}

还有个隐蔽约束：文件绑定上传时的应用——同一个文件换了应用（重新导入的 app）引用就失效，每个被测应用要独立上传。

5.3 运行结果

测试图是程序生成的：蓝色背景 + 左上角红色方块。qwen-vl-plus 识别结果（3.9 秒）：

这张图片非常简洁，主要由两种颜色构成：蓝色和红色。整体布局：大部分区域被纯蓝色填充；左上角有一个小的红色正方形……红色正方形在蓝色背景的衬托下显得格外突出。

颜色、位置、布局描述全部准确——图片直传链路完整可用。

六、运行验证汇总

七、实战坑：6 个坑

八、结论：两个能力都能直接交付

• 审批流：数组 + Iteration + human-input，天然支持逐项确认——「任务清单审批」「批量内容审核」这类需求可以直接做，不用再拆多次调用
• 图片理解：v1 上传 + file 变量 + vision 直传，链路完整——「图片描述」「文档视觉识别」「拍照报障」这类需求落地成本大幅下降

两个能力共同的提醒：1.17 的迭代格式是破坏性变更，存量迭代 DSL 要迁移；文件链路要按 service API 的规矩走。踩过这些坑，这两条链路就是顺手的能力。

📚 本系列其他篇：一、升级总览与 5 件事 ｜ 二、Agent V2 节点与技能包实测

实验文档与源码获取

• 循环内人工输入实验记录（实验 04，含完整迭代 DSL）
• 多模态图片直传实验记录（实验 05，含完整 vision 配置）
• 相关 DSL 与应用导出：dify-108 实验工作区

本文基于 Dify 1.17.0 + Hermes Agent v0.21.0 实测，配置在不同版本间可能变化，使用前请确认版本。AI 参与创作声明：本文由 AI 辅助写作，内容基于作者真实实测记录。